/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.http.server.reactive;

import java.net.InetSocketAddress;
import java.net.URI;
import java.util.function.Consumer;

import org.springframework.http.HttpCookie;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.HttpRequest;
import org.springframework.http.ReactiveHttpInputMessage;
import org.springframework.http.server.RequestPath;
import org.springframework.lang.Nullable;
import org.springframework.util.MultiValueMap;

/**
 * Represents a reactive server-side HTTP request
 *
 * @author Arjen Poutsma
 * @author Rossen Stoyanchev
 * @since 5.0
 */
public interface ServerHttpRequest extends HttpRequest, ReactiveHttpInputMessage {

    /**
     * Returns a structured representation of the request path including the
     * context path + path within application portions, path segments with
     * encoded and decoded values, and path parameters.
     */
    RequestPath getPath();

    /**
     * Return a read-only map with parsed and decoded query parameter values.
     */
    MultiValueMap<String, String> getQueryParams();

    /**
     * Return a read-only map of cookies sent by the client.
     */
    MultiValueMap<String, HttpCookie> getCookies();

    /**
     * Return the remote address where this request is connected to, if available.
     */
    @Nullable
    default InetSocketAddress getRemoteAddress() {
        return null;
    }

    /**
     * Return the SSL session information if the request has been transmitted
     * over a secure protocol including SSL certificates, if available.
     *
     * @return the session information, or {@code null} if none available
     * @since 5.0.2
     */
    @Nullable
    default SslInfo getSslInfo() {
        return null;
    }

    /**
     * Return a builder to mutate properties of this request by wrapping it
     * with {@link ServerHttpRequestDecorator} and returning either mutated
     * values or delegating back to this instance.
     */
    default ServerHttpRequest.Builder mutate() {
        return new DefaultServerHttpRequestBuilder(this);
    }


    /**
     * Builder for mutating an existing {@link ServerHttpRequest}.
     */
    interface Builder {

        /**
         * Set the HTTP method to return.
         */
        Builder method(HttpMethod httpMethod);

        /**
         * Set the URI to return.
         */
        Builder uri(URI uri);

        /**
         * Set the path to use instead of the {@code "rawPath"} of
         * {@link ServerHttpRequest#getURI()}.
         */
        Builder path(String path);

        /**
         * Set the contextPath to use.
         */
        Builder contextPath(String contextPath);

        /**
         * Set or override the specified header.
         */
        Builder header(String key, String value);

        /**
         * Manipulate this request's headers with the given consumer. The
         * headers provided to the consumer are "live", so that the consumer can be used to
         * {@linkplain HttpHeaders#set(String, String) overwrite} existing header values,
         * {@linkplain HttpHeaders#remove(Object) remove} values, or use any of the other
         * {@link HttpHeaders} methods.
         *
         * @param headersConsumer a function that consumes the {@code HttpHeaders}
         * @return this builder
         */
        Builder headers(Consumer<HttpHeaders> headersConsumer);

        /**
         * Build a {@link ServerHttpRequest} decorator with the mutated properties.
         */
        ServerHttpRequest build();
    }

}
